Birdee binding Functions for Python

This chapter lists the functions provided by Birdee that can be called from Python. Note that some of the functions are only avaliable in generative script mode and is invisible for embeded scripts in Birdee source code. The following documents uses python's type hint syntax to show the prototypes of the APIs.

Compiler Controling in generative script

def clear_compile_unit()

Only in generative script mode. Reset the compiler and clear all parsed data of the current compiled program. The compiler will be ready to compile a new program.

def top_level(source: str)

Only in generative script mode. It accepts a string that contains one or more lines of top-level Birdee code. It will parse the source string into AST and insert the AST nodes into the top-level of the currently compiled program. A TokenizerException may be throw if parsing the source into AST fails. Note: this function only convert the source code into AST. You may need to call process_top_level to check the correctness of the parsed AST. You can call top_level for multiple times to insert several pieces of code into the top-level. The latter call to this function will append the code to the AST list of the previous call to this function. 

def process_top_level()

Only in generative script mode. Process the AST that is generated by calls to the function top_level. A CompileException may be throw if there is an error in the AST (e.g. type mismatch for variable assignment). You can only call this function one time before you reset the compiler by clear_compile_unit.

def generate()

Only in generative script mode. Generate an object file based on processed top-level AST. You should call process_top_level before calling this function. The path of the output file is specified in the command line argument of the compiler.

def set_print_ir(flag: bool)

Only in generative script mode. Set whether the compiler will output the LLVM IR for the generated program to stderr after calling generate. If the flag is True, the printing behavior is on.

Typical workflow of a generative script

In a typical generative script, it may first call top_level to feed the source code into the compiler. Then it calls process_top_level to process the program. Optionally, it calls generate to generate the object file of the code. It may also optionally call clear_compile_unit to reset the compiler and reuse the compiler for another Birdee program.

Environment queries

def get_os_name() -> str

Get the name of target OS. Note: the target OS is what the output object file is compiled for and it may be different from the OS that the compiler runs on. Returns "windows", "linux" or "unknown target name".

def get_target_bits() -> int

Get the bits of the target object file. Returns an integer, maybe 64 or 32.

Compiler state queries and control

def imports(module_name: str)

Import a Birdee module. It has the same effect as the Birdee keyword import in Birdee code. The difference is that it is a Python function. It accepts a string which is the module name or a symbol within a module. e.g. "concurrent.threading" or "concurrent.threading:thread" are valid input for this function.

def get_cur_script() -> ScriptAST

Can only be called within a embeded script ({@...@}) for statements. Returns the current ScriptAST that the script is in.

def class_body(clz: ClassAST, source: str)

Insert a chunk of code in the class body of a class. The class is specified by the argument clz. The code is specified in the argument source. Note that only one function or one line of member variable is added to the class in a call to class_body at a time. If your source contains more than one line to insert and it is not a function definition, the lines after the first valid member definition will be ignored. A single line of multiple member variable definition is accepted in this case, since the members are defined in one single line. A member function that occupies multiple lines are also accepted by this function.

def resolve_type(type: ResolvedType) -> int

Get the size of a type, in bytes. Currently the input type cannot a struct type. 

def expr(source: str) -> StatementAST_UniquePtr

Converts a Birdee source code string into an AST. Expecting an expression. Takes the ownership of the returned AST.

def stmt(source: str) -> StatementAST_UniquePtr

Converts a Birdee source code string into an AST. Expecting an statement. Takes the ownership of the returned AST.

def set_ast(ast: StatementAST_UniquePtr)

Can only be called in embeded script for statements. Sets the current script AST with the given AST node. It will take the ownership of the input AST. You can call this function multiple times to combine multiple lines of Birdee code into in ScriptAST node. All of the Birdee code set into the ScriptAST will be generated and executed. The value of the resulting ScriptAST node will be the result of the first Birdee code set into the ast.

def resolve_type(source: str) -> ResolvedType

Convert a string representation of a Birdee type into a ResolvedType AST. The input string should be any valid Birdee type in the current script context, e.g. "int", "string". 

def set_type(type: ResolvedType)

Can only be called in embeded script for types. Sets the current type script AST with the given resolved type.

def get_cur_func() -> FunctionAST

Returns the reference to the current function AST that the script is in, or None if is not in a function.

def get_cur_class() -> ClassAST

Returns the reference to the current class AST that the script is in, or None if is not in a class.

def get_func(name: str) -> FunctionAST

Find the reference to the function AST with a given name, or None if it does not exist.

def get_top_level(name: str) -> StatementASTList

Get the list of statements for the top-level code.

def get_compile_error() -> CompileError

Get the current compile error. You should call it when a CompileException occurs for more information on the error.

def get_tokenizer_error() -> TokenizerError

Get the current tokenizer error. You should call it when a TokenizerException occurs for more information on the error.